<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>Beyond the Basics &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <script type="text/javascript" src="../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../about.html" >
    <link rel="index" title="Index" href="../genindex.html" >
    <link rel="search" title="Search" href="../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../index.html" >
    <link rel="up" title="Using NumPy C-API" href="c-info.html" >
    <link rel="next" title="NumPy Reference" href="../reference/index.html" >
    <link rel="prev" title="Writing your own ufunc" href="c-info.ufunc-tutorial.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../index.html">
      <img border=0 alt="NumPy" src="../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="index.html" >NumPy User Guide</a></li>
          <li class="active"><a href="c-info.html" accesskey="U">Using NumPy C-API</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="../reference/index.html" title="NumPy Reference"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="c-info.ufunc-tutorial.html" title="Writing your own ufunc"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Beyond the Basics</a><ul>
<li><a class="reference internal" href="#iterating-over-elements-in-the-array">Iterating over elements in the array</a><ul>
<li><a class="reference internal" href="#basic-iteration">Basic Iteration</a></li>
<li><a class="reference internal" href="#iterating-over-all-but-one-axis">Iterating over all but one axis</a></li>
<li><a class="reference internal" href="#iterating-over-multiple-arrays">Iterating over multiple arrays</a></li>
<li><a class="reference internal" href="#broadcasting-over-multiple-arrays">Broadcasting over multiple arrays</a></li>
</ul>
</li>
<li><a class="reference internal" href="#user-defined-data-types">User-defined data-types</a><ul>
<li><a class="reference internal" href="#adding-the-new-data-type">Adding the new data-type</a></li>
<li><a class="reference internal" href="#registering-a-casting-function">Registering a casting function</a></li>
<li><a class="reference internal" href="#registering-coercion-rules">Registering coercion rules</a></li>
<li><a class="reference internal" href="#registering-a-ufunc-loop">Registering a ufunc loop</a></li>
</ul>
</li>
<li><a class="reference internal" href="#subtyping-the-ndarray-in-c">Subtyping the ndarray in C</a><ul>
<li><a class="reference internal" href="#creating-sub-types">Creating sub-types</a></li>
<li><a class="reference internal" href="#specific-features-of-ndarray-sub-typing">Specific features of ndarray sub-typing</a><ul>
<li><a class="reference internal" href="#the-array-finalize-method">The __array_finalize__ method</a></li>
<li><a class="reference internal" href="#the-array-priority-attribute">The __array_priority__ attribute</a></li>
<li><a class="reference internal" href="#the-array-wrap-method">The __array_wrap__ method</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="c-info.ufunc-tutorial.html"
                        title="previous chapter">Writing your own ufunc</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="../reference/index.html"
                        title="next chapter">NumPy Reference</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="beyond-the-basics">
<h1>Beyond the Basics<a class="headerlink" href="#beyond-the-basics" title="Permalink to this headline">¶</a></h1>
<div class="line-block">
<div class="line">The voyage of discovery is not in seeking new landscapes but in having</div>
<div class="line">new eyes.</div>
<div class="line">— <em>Marcel Proust</em></div>
</div>
<div class="line-block">
<div class="line">Discovery is seeing what everyone else has seen and thinking what no</div>
<div class="line">one else has thought.</div>
<div class="line">— <em>Albert Szent-Gyorgi</em></div>
</div>
<div class="section" id="iterating-over-elements-in-the-array">
<h2>Iterating over elements in the array<a class="headerlink" href="#iterating-over-elements-in-the-array" title="Permalink to this headline">¶</a></h2>
<div class="section" id="basic-iteration">
<span id="sec-array-iterator"></span><h3>Basic Iteration<a class="headerlink" href="#basic-iteration" title="Permalink to this headline">¶</a></h3>
<p>One common algorithmic requirement is to be able to walk over all
elements in a multidimensional array. The array iterator object makes
this easy to do in a generic way that works for arrays of any
dimension. Naturally, if you know the number of dimensions you will be
using, then you can always write nested for loops to accomplish the
iteration. If, however, you want to write code that works with any
number of dimensions, then you can make use of the array iterator. An
array iterator object is returned when accessing the .flat attribute
of an array.</p>
<p id="index-0">Basic usage is to call <a class="reference internal" href="../reference/c-api/array.html#c.PyArray_IterNew" title="PyArray_IterNew"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_IterNew</span></code></a> ( <code class="docutils literal notranslate"><span class="pre">array</span></code> ) where array
is an ndarray object (or one of its sub-classes). The returned object
is an array-iterator object (the same object returned by the .flat
attribute of the ndarray). This object is usually cast to
PyArrayIterObject* so that its members can be accessed. The only
members that are needed are <code class="docutils literal notranslate"><span class="pre">iter-&gt;size</span></code> which contains the total
size of the array, <code class="docutils literal notranslate"><span class="pre">iter-&gt;index</span></code>, which contains the current 1-d
index into the array, and <code class="docutils literal notranslate"><span class="pre">iter-&gt;dataptr</span></code> which is a pointer to the
data for the current element of the array.  Sometimes it is also
useful to access <code class="docutils literal notranslate"><span class="pre">iter-&gt;ao</span></code> which is a pointer to the underlying
ndarray object.</p>
<p>After processing data at the current element of the array, the next
element of the array can be obtained using the macro
<a class="reference internal" href="../reference/c-api/array.html#c.PyArray_ITER_NEXT" title="PyArray_ITER_NEXT"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_ITER_NEXT</span></code></a> ( <code class="docutils literal notranslate"><span class="pre">iter</span></code> ). The iteration always proceeds in a
C-style contiguous fashion (last index varying the fastest). The
<a class="reference internal" href="../reference/c-api/array.html#c.PyArray_ITER_GOTO" title="PyArray_ITER_GOTO"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_ITER_GOTO</span></code></a> ( <code class="docutils literal notranslate"><span class="pre">iter</span></code>, <code class="docutils literal notranslate"><span class="pre">destination</span></code> ) can be used to
jump to a particular point in the array, where <code class="docutils literal notranslate"><span class="pre">destination</span></code> is an
array of npy_intp data-type with space to handle at least the number
of dimensions in the underlying array. Occasionally it is useful to
use <a class="reference internal" href="../reference/c-api/array.html#c.PyArray_ITER_GOTO1D" title="PyArray_ITER_GOTO1D"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_ITER_GOTO1D</span></code></a> ( <code class="docutils literal notranslate"><span class="pre">iter</span></code>, <code class="docutils literal notranslate"><span class="pre">index</span></code> ) which will jump
to the 1-d index given by the value of <code class="docutils literal notranslate"><span class="pre">index</span></code>. The most common
usage, however, is given in the following example.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span> <span class="o">*</span><span class="n">obj</span><span class="p">;</span> <span class="cm">/* assumed to be some ndarray object */</span>
<span class="n">PyArrayIterObject</span> <span class="o">*</span><span class="n">iter</span><span class="p">;</span>
<span class="p">...</span>
<span class="n">iter</span> <span class="o">=</span> <span class="p">(</span><span class="n">PyArrayIterObject</span> <span class="o">*</span><span class="p">)</span><span class="n">PyArray_IterNew</span><span class="p">(</span><span class="n">obj</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">iter</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span> <span class="k">goto</span> <span class="n">fail</span><span class="p">;</span>   <span class="cm">/* Assume fail has clean-up code */</span>
<span class="k">while</span> <span class="p">(</span><span class="n">iter</span><span class="o">-&gt;</span><span class="n">index</span> <span class="o">&lt;</span> <span class="n">iter</span><span class="o">-&gt;</span><span class="n">size</span><span class="p">)</span> <span class="p">{</span>
    <span class="cm">/* do something with the data at it-&gt;dataptr */</span>
    <span class="n">PyArray_ITER_NEXT</span><span class="p">(</span><span class="n">it</span><span class="p">);</span>
<span class="p">}</span>
<span class="p">...</span>
</pre></div>
</div>
<p>You can also use <a class="reference internal" href="../reference/c-api/array.html#c.PyArrayIter_Check" title="PyArrayIter_Check"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArrayIter_Check</span></code></a> ( <code class="docutils literal notranslate"><span class="pre">obj</span></code> ) to ensure you have
an iterator object and <a class="reference internal" href="../reference/c-api/array.html#c.PyArray_ITER_RESET" title="PyArray_ITER_RESET"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_ITER_RESET</span></code></a> ( <code class="docutils literal notranslate"><span class="pre">iter</span></code> ) to reset an
iterator object back to the beginning of the array.</p>
<p>It should be emphasized at this point that you may not need the array
iterator if your array is already contiguous (using an array iterator
will work but will be slower than the fastest code you could write).
The major purpose of array iterators is to encapsulate iteration over
N-dimensional arrays with arbitrary strides. They are used in many,
many places in the NumPy source code itself. If you already know your
array is contiguous (Fortran or C), then simply adding the element-
size to a running pointer variable will step you through the array
very efficiently. In other words, code like this will probably be
faster for you in the contiguous case (assuming doubles).</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">npy_intp</span> <span class="n">size</span><span class="p">;</span>
<span class="kt">double</span> <span class="o">*</span><span class="n">dptr</span><span class="p">;</span>  <span class="cm">/* could make this any variable type */</span>
<span class="n">size</span> <span class="o">=</span> <span class="n">PyArray_SIZE</span><span class="p">(</span><span class="n">obj</span><span class="p">);</span>
<span class="n">dptr</span> <span class="o">=</span> <span class="n">PyArray_DATA</span><span class="p">(</span><span class="n">obj</span><span class="p">);</span>
<span class="k">while</span><span class="p">(</span><span class="n">size</span><span class="o">--</span><span class="p">)</span> <span class="p">{</span>
   <span class="cm">/* do something with the data at dptr */</span>
   <span class="n">dptr</span><span class="o">++</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="iterating-over-all-but-one-axis">
<h3>Iterating over all but one axis<a class="headerlink" href="#iterating-over-all-but-one-axis" title="Permalink to this headline">¶</a></h3>
<p>A common algorithm is to loop over all elements of an array and
perform some function with each element by issuing a function call. As
function calls can be time consuming, one way to speed up this kind of
algorithm is to write the function so it takes a vector of data and
then write the iteration so the function call is performed for an
entire dimension of data at a time. This increases the amount of work
done per function call, thereby reducing the function-call over-head
to a small(er) fraction of the total time. Even if the interior of the
loop is performed without a function call it can be advantageous to
perform the inner loop over the dimension with the highest number of
elements to take advantage of speed enhancements available on micro-
processors that use pipelining to enhance fundmental operations.</p>
<p>The <a class="reference internal" href="../reference/c-api/array.html#c.PyArray_IterAllButAxis" title="PyArray_IterAllButAxis"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_IterAllButAxis</span></code></a> ( <code class="docutils literal notranslate"><span class="pre">array</span></code>, <code class="docutils literal notranslate"><span class="pre">&amp;dim</span></code> ) constructs an
iterator object that is modified so that it will not iterate over the
dimension indicated by dim. The only restriction on this iterator
object, is that the <code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_Iter_GOTO1D</span></code> ( <code class="docutils literal notranslate"><span class="pre">it</span></code>, <code class="docutils literal notranslate"><span class="pre">ind</span></code> ) macro
cannot be used (thus flat indexing won’t work either if you pass this
object back to Python — so you shouldn’t do this). Note that the
returned object from this routine is still usually cast to
PyArrayIterObject *. All that’s been done is to modify the strides
and dimensions of the returned iterator to simulate iterating over
array[…,0,…] where 0 is placed on the
<img class="math" src="../_images/math/8d7dca64fa3e5bc80c26eb243d79bc0bb96f42b6.svg" alt="\textrm{dim}^{\textrm{th}}"/> dimension. If dim is negative, then
the dimension with the largest axis is found and used.</p>
</div>
<div class="section" id="iterating-over-multiple-arrays">
<h3>Iterating over multiple arrays<a class="headerlink" href="#iterating-over-multiple-arrays" title="Permalink to this headline">¶</a></h3>
<p>Very often, it is desirable to iterate over several arrays at the
same time. The universal functions are an example of this kind of
behavior. If all you want to do is iterate over arrays with the same
shape, then simply creating several iterator objects is the standard
procedure. For example, the following code iterates over two arrays
assumed to be the same shape and size (actually obj1 just has to have
at least as many total elements as does obj2):</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/* It is already assumed that obj1 and obj2</span>
<span class="cm">   are ndarrays of the same shape and size.</span>
<span class="cm">*/</span>
<span class="n">iter1</span> <span class="o">=</span> <span class="p">(</span><span class="n">PyArrayIterObject</span> <span class="o">*</span><span class="p">)</span><span class="n">PyArray_IterNew</span><span class="p">(</span><span class="n">obj1</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">iter1</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span> <span class="k">goto</span> <span class="n">fail</span><span class="p">;</span>
<span class="n">iter2</span> <span class="o">=</span> <span class="p">(</span><span class="n">PyArrayIterObject</span> <span class="o">*</span><span class="p">)</span><span class="n">PyArray_IterNew</span><span class="p">(</span><span class="n">obj2</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">iter2</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span> <span class="k">goto</span> <span class="n">fail</span><span class="p">;</span>  <span class="cm">/* assume iter1 is DECREF&#39;d at fail */</span>
<span class="k">while</span> <span class="p">(</span><span class="n">iter2</span><span class="o">-&gt;</span><span class="n">index</span> <span class="o">&lt;</span> <span class="n">iter2</span><span class="o">-&gt;</span><span class="n">size</span><span class="p">)</span>  <span class="p">{</span>
    <span class="cm">/* process with iter1-&gt;dataptr and iter2-&gt;dataptr */</span>
    <span class="n">PyArray_ITER_NEXT</span><span class="p">(</span><span class="n">iter1</span><span class="p">);</span>
    <span class="n">PyArray_ITER_NEXT</span><span class="p">(</span><span class="n">iter2</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="broadcasting-over-multiple-arrays">
<h3>Broadcasting over multiple arrays<a class="headerlink" href="#broadcasting-over-multiple-arrays" title="Permalink to this headline">¶</a></h3>
<p id="index-1">When multiple arrays are involved in an operation, you may want to use the
same broadcasting rules that the math operations (<em>i.e.</em> the ufuncs) use.
This can be done easily using the <a class="reference internal" href="../reference/c-api/types-and-structures.html#c.PyArrayMultiIterObject" title="PyArrayMultiIterObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyArrayMultiIterObject</span></code></a>.  This is
the object returned from the Python command numpy.broadcast and it is almost
as easy to use from C. The function
<a class="reference internal" href="../reference/c-api/array.html#c.PyArray_MultiIterNew" title="PyArray_MultiIterNew"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_MultiIterNew</span></code></a> ( <code class="docutils literal notranslate"><span class="pre">n</span></code>, <code class="docutils literal notranslate"><span class="pre">...</span></code> ) is used (with <code class="docutils literal notranslate"><span class="pre">n</span></code> input
objects in place of <code class="docutils literal notranslate"><span class="pre">...</span></code> ). The input objects can be arrays or anything
that can be converted into an array. A pointer to a PyArrayMultiIterObject is
returned.  Broadcasting has already been accomplished which adjusts the
iterators so that all that needs to be done to advance to the next element in
each array is for PyArray_ITER_NEXT to be called for each of the inputs. This
incrementing is automatically performed by
<a class="reference internal" href="../reference/c-api/array.html#c.PyArray_MultiIter_NEXT" title="PyArray_MultiIter_NEXT"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_MultiIter_NEXT</span></code></a> ( <code class="docutils literal notranslate"><span class="pre">obj</span></code> ) macro (which can handle a
multiterator <code class="docutils literal notranslate"><span class="pre">obj</span></code> as either a <code class="xref c c-type docutils literal notranslate"><span class="pre">PyArrayMultiObject</span> <span class="pre">*</span></code> or a
<a class="reference external" href="https://docs.python.org/dev/c-api/structures.html#c.PyObject" title="(in Python v3.9)"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span> <span class="pre">*</span></code></a>). The data from input number <code class="docutils literal notranslate"><span class="pre">i</span></code> is available using
<a class="reference internal" href="../reference/c-api/array.html#c.PyArray_MultiIter_DATA" title="PyArray_MultiIter_DATA"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_MultiIter_DATA</span></code></a> ( <code class="docutils literal notranslate"><span class="pre">obj</span></code>, <code class="docutils literal notranslate"><span class="pre">i</span></code> ) and the total (broadcasted)
size as <code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_MultiIter_SIZE</span></code> ( <code class="docutils literal notranslate"><span class="pre">obj</span></code>). An example of using this
feature follows.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">mobj</span> <span class="o">=</span> <span class="n">PyArray_MultiIterNew</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">obj1</span><span class="p">,</span> <span class="n">obj2</span><span class="p">);</span>
<span class="n">size</span> <span class="o">=</span> <span class="n">PyArray_MultiIter_SIZE</span><span class="p">(</span><span class="n">obj</span><span class="p">);</span>
<span class="k">while</span><span class="p">(</span><span class="n">size</span><span class="o">--</span><span class="p">)</span> <span class="p">{</span>
    <span class="n">ptr1</span> <span class="o">=</span> <span class="n">PyArray_MultiIter_DATA</span><span class="p">(</span><span class="n">mobj</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
    <span class="n">ptr2</span> <span class="o">=</span> <span class="n">PyArray_MultiIter_DATA</span><span class="p">(</span><span class="n">mobj</span><span class="p">,</span> <span class="mi">1</span><span class="p">);</span>
    <span class="cm">/* code using contents of ptr1 and ptr2 */</span>
    <span class="n">PyArray_MultiIter_NEXT</span><span class="p">(</span><span class="n">mobj</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The function <a class="reference internal" href="../reference/c-api/array.html#c.PyArray_RemoveSmallest" title="PyArray_RemoveSmallest"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_RemoveSmallest</span></code></a> ( <code class="docutils literal notranslate"><span class="pre">multi</span></code> ) can be used to
take a multi-iterator object and adjust all the iterators so that
iteration does not take place over the largest dimension (it makes
that dimension of size 1). The code being looped over that makes use
of the pointers will very-likely also need the strides data for each
of the iterators. This information is stored in
multi-&gt;iters[i]-&gt;strides.</p>
<p id="index-2">There are several examples of using the multi-iterator in the NumPy
source code as it makes N-dimensional broadcasting-code very simple to
write. Browse the source for more examples.</p>
</div>
</div>
<div class="section" id="user-defined-data-types">
<span id="user-user-defined-data-types"></span><h2>User-defined data-types<a class="headerlink" href="#user-defined-data-types" title="Permalink to this headline">¶</a></h2>
<p>NumPy comes with 24 builtin data-types. While this covers a large
majority of possible use cases, it is conceivable that a user may have
a need for an additional data-type. There is some support for adding
an additional data-type into the NumPy system. This additional data-
type will behave much like a regular data-type except ufuncs must have
1-d loops registered to handle it separately. Also checking for
whether or not other data-types can be cast “safely” to and from this
new type or not will always return “can cast” unless you also register
which types your new data-type can be cast to and from.</p>
<p>The NumPy source code includes an example of a custom data-type as part
of its test suite. The file <code class="docutils literal notranslate"><span class="pre">_rational_tests.c.src</span></code> in the source code
directory  <code class="docutils literal notranslate"><span class="pre">numpy/numpy/core/src/umath/</span></code> contains an implementation of
a data-type that represents a rational number as the ratio of two 32 bit
integers.</p>
<div class="section" id="adding-the-new-data-type">
<span id="index-3"></span><h3>Adding the new data-type<a class="headerlink" href="#adding-the-new-data-type" title="Permalink to this headline">¶</a></h3>
<p>To begin to make use of the new data-type, you need to first define a
new Python type to hold the scalars of your new data-type. It should
be acceptable to inherit from one of the array scalars if your new
type has a binary compatible layout. This will allow your new data
type to have the methods and attributes of array scalars. New data-
types must have a fixed memory size (if you want to define a data-type
that needs a flexible representation, like a variable-precision
number, then use a pointer to the object as the data-type). The memory
layout of the object structure for the new Python type must be
PyObject_HEAD followed by the fixed-size memory needed for the data-
type. For example, a suitable structure for the new Python type is:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
   <span class="n">PyObject_HEAD</span><span class="p">;</span>
   <span class="n">some_data_type</span> <span class="n">obval</span><span class="p">;</span>
   <span class="cm">/* the name can be whatever you want */</span>
<span class="p">}</span> <span class="n">PySomeDataTypeObject</span><span class="p">;</span>
</pre></div>
</div>
<p>After you have defined a new Python type object, you must then define
a new <a class="reference internal" href="../reference/c-api/types-and-structures.html#c.PyArray_Descr" title="PyArray_Descr"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyArray_Descr</span></code></a> structure whose typeobject member will contain a
pointer to the data-type you’ve just defined. In addition, the
required functions in the “.f” member must be defined: nonzero,
copyswap, copyswapn, setitem, getitem, and cast. The more functions in
the “.f” member you define, however, the more useful the new data-type
will be.  It is very important to initialize unused functions to NULL.
This can be achieved using <a class="reference internal" href="../reference/c-api/array.html#c.PyArray_InitArrFuncs" title="PyArray_InitArrFuncs"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_InitArrFuncs</span></code></a> (f).</p>
<p>Once a new <a class="reference internal" href="../reference/c-api/types-and-structures.html#c.PyArray_Descr" title="PyArray_Descr"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyArray_Descr</span></code></a> structure is created and filled with the
needed information and useful functions you call
<a class="reference internal" href="../reference/c-api/array.html#c.PyArray_RegisterDataType" title="PyArray_RegisterDataType"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_RegisterDataType</span></code></a> (new_descr). The return value from this
call is an integer providing you with a unique type_number that
specifies your data-type. This type number should be stored and made
available by your module so that other modules can use it to recognize
your data-type (the other mechanism for finding a user-defined
data-type number is to search based on the name of the type-object
associated with the data-type using <code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_TypeNumFromName</span></code> ).</p>
</div>
<div class="section" id="registering-a-casting-function">
<h3>Registering a casting function<a class="headerlink" href="#registering-a-casting-function" title="Permalink to this headline">¶</a></h3>
<p>You may want to allow builtin (and other user-defined) data-types to
be cast automatically to your data-type. In order to make this
possible, you must register a casting function with the data-type you
want to be able to cast from. This requires writing low-level casting
functions for each conversion you want to support and then registering
these functions with the data-type descriptor. A low-level casting
function has the signature.</p>
<dl class="function">
<dt id="c.castfunc">
void <code class="sig-name descname">castfunc</code><span class="sig-paren">(</span>void*<em> from</em>, void*<em> to</em>, <a class="reference internal" href="../reference/c-api/dtype.html#c.npy_intp" title="npy_intp">npy_intp</a><em> n</em>, void*<em> fromarr</em>, void*<em> toarr</em><span class="sig-paren">)</span><a class="headerlink" href="#c.castfunc" title="Permalink to this definition">¶</a></dt>
<dd><p>Cast <code class="docutils literal notranslate"><span class="pre">n</span></code> elements <code class="docutils literal notranslate"><span class="pre">from</span></code> one type <code class="docutils literal notranslate"><span class="pre">to</span></code> another. The data to
cast from is in a contiguous, correctly-swapped and aligned chunk
of memory pointed to by from. The buffer to cast to is also
contiguous, correctly-swapped and aligned. The fromarr and toarr
arguments should only be used for flexible-element-sized arrays
(string, unicode, void).</p>
</dd></dl>

<p>An example castfunc is:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">void</span>
<span class="nf">double_to_float</span><span class="p">(</span><span class="kt">double</span> <span class="o">*</span><span class="n">from</span><span class="p">,</span> <span class="kt">float</span><span class="o">*</span> <span class="n">to</span><span class="p">,</span> <span class="n">npy_intp</span> <span class="n">n</span><span class="p">,</span>
                <span class="kt">void</span><span class="o">*</span> <span class="n">ignore1</span><span class="p">,</span> <span class="kt">void</span><span class="o">*</span> <span class="n">ignore2</span><span class="p">)</span> <span class="p">{</span>
    <span class="k">while</span> <span class="p">(</span><span class="n">n</span><span class="o">--</span><span class="p">)</span> <span class="p">{</span>
          <span class="p">(</span><span class="o">*</span><span class="n">to</span><span class="o">++</span><span class="p">)</span> <span class="o">=</span> <span class="p">(</span><span class="kt">double</span><span class="p">)</span> <span class="o">*</span><span class="p">(</span><span class="n">from</span><span class="o">++</span><span class="p">);</span>
    <span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This could then be registered to convert doubles to floats using the
code:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">doub</span> <span class="o">=</span> <span class="n">PyArray_DescrFromType</span><span class="p">(</span><span class="n">NPY_DOUBLE</span><span class="p">);</span>
<span class="n">PyArray_RegisterCastFunc</span><span class="p">(</span><span class="n">doub</span><span class="p">,</span> <span class="n">NPY_FLOAT</span><span class="p">,</span>
     <span class="p">(</span><span class="n">PyArray_VectorUnaryFunc</span> <span class="o">*</span><span class="p">)</span><span class="n">double_to_float</span><span class="p">);</span>
<span class="n">Py_DECREF</span><span class="p">(</span><span class="n">doub</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="section" id="registering-coercion-rules">
<h3>Registering coercion rules<a class="headerlink" href="#registering-coercion-rules" title="Permalink to this headline">¶</a></h3>
<p>By default, all user-defined data-types are not presumed to be safely
castable to any builtin data-types. In addition builtin data-types are
not presumed to be safely castable to user-defined data-types. This
situation limits the ability of user-defined data-types to participate
in the coercion system used by ufuncs and other times when automatic
coercion takes place in NumPy. This can be changed by registering
data-types as safely castable from a particular data-type object. The
function <a class="reference internal" href="../reference/c-api/array.html#c.PyArray_RegisterCanCast" title="PyArray_RegisterCanCast"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_RegisterCanCast</span></code></a> (from_descr, totype_number,
scalarkind) should be used to specify that the data-type object
from_descr can be cast to the data-type with type number
totype_number. If you are not trying to alter scalar coercion rules,
then use <a class="reference internal" href="../reference/c-api/array.html#c.NPY_NOSCALAR" title="NPY_NOSCALAR"><code class="xref c c-data docutils literal notranslate"><span class="pre">NPY_NOSCALAR</span></code></a> for the scalarkind argument.</p>
<p>If you want to allow your new data-type to also be able to share in
the scalar coercion rules, then you need to specify the scalarkind
function in the data-type object’s “.f” member to return the kind of
scalar the new data-type should be seen as (the value of the scalar is
available to that function). Then, you can register data-types that
can be cast to separately for each scalar kind that may be returned
from your user-defined data-type. If you don’t register scalar
coercion handling, then all of your user-defined data-types will be
seen as <a class="reference internal" href="../reference/c-api/array.html#c.NPY_NOSCALAR" title="NPY_NOSCALAR"><code class="xref c c-data docutils literal notranslate"><span class="pre">NPY_NOSCALAR</span></code></a>.</p>
</div>
<div class="section" id="registering-a-ufunc-loop">
<h3>Registering a ufunc loop<a class="headerlink" href="#registering-a-ufunc-loop" title="Permalink to this headline">¶</a></h3>
<p>You may also want to register low-level ufunc loops for your data-type
so that an ndarray of your data-type can have math applied to it
seamlessly. Registering a new loop with exactly the same arg_types
signature, silently replaces any previously registered loops for that
data-type.</p>
<p>Before you can register a 1-d loop for a ufunc, the ufunc must be
previously created. Then you call <a class="reference internal" href="../reference/c-api/ufunc.html#c.PyUFunc_RegisterLoopForType" title="PyUFunc_RegisterLoopForType"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUFunc_RegisterLoopForType</span></code></a>
(…) with the information needed for the loop. The return value of
this function is <code class="docutils literal notranslate"><span class="pre">0</span></code> if the process was successful and <code class="docutils literal notranslate"><span class="pre">-1</span></code> with
an error condition set if it was not successful.</p>
</div>
</div>
<div class="section" id="subtyping-the-ndarray-in-c">
<span id="index-4"></span><h2>Subtyping the ndarray in C<a class="headerlink" href="#subtyping-the-ndarray-in-c" title="Permalink to this headline">¶</a></h2>
<p>One of the lesser-used features that has been lurking in Python since
2.2 is the ability to sub-class types in C. This facility is one of
the important reasons for basing NumPy off of the Numeric code-base
which was already in C. A sub-type in C allows much more flexibility
with regards to memory management. Sub-typing in C is not difficult
even if you have only a rudimentary understanding of how to create new
types for Python. While it is easiest to sub-type from a single parent
type, sub-typing from multiple parent types is also possible. Multiple
inheritance in C is generally less useful than it is in Python because
a restriction on Python sub-types is that they have a binary
compatible memory layout. Perhaps for this reason, it is somewhat
easier to sub-type from a single parent type.</p>
<p id="index-5">All C-structures corresponding to Python objects must begin with
<a class="reference external" href="https://docs.python.org/dev/c-api/structures.html#c.PyObject_HEAD" title="(in Python v3.9)"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyObject_HEAD</span></code></a> (or <a class="reference external" href="https://docs.python.org/dev/c-api/structures.html#c.PyObject_VAR_HEAD" title="(in Python v3.9)"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyObject_VAR_HEAD</span></code></a>). In the same
way, any sub-type must have a C-structure that begins with exactly the
same memory layout as the parent type (or all of the parent types in
the case of multiple-inheritance). The reason for this is that Python
may attempt to access a member of the sub-type structure as if it had
the parent structure ( <em>i.e.</em> it will cast a given pointer to a
pointer to the parent structure and then dereference one of it’s
members). If the memory layouts are not compatible, then this attempt
will cause unpredictable behavior (eventually leading to a memory
violation and program crash).</p>
<p>One of the elements in <a class="reference external" href="https://docs.python.org/dev/c-api/structures.html#c.PyObject_HEAD" title="(in Python v3.9)"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyObject_HEAD</span></code></a> is a pointer to a
type-object structure. A new Python type is created by creating a new
type-object structure and populating it with functions and pointers to
describe the desired behavior of the type. Typically, a new
C-structure is also created to contain the instance-specific
information needed for each object of the type as well. For example,
<a class="reference internal" href="../reference/c-api/types-and-structures.html#c.PyArray_Type" title="PyArray_Type"><code class="xref c c-data docutils literal notranslate"><span class="pre">&amp;PyArray_Type</span></code></a> is a pointer to the type-object table for the ndarray
while a <a class="reference internal" href="../reference/c-api/types-and-structures.html#c.PyArrayObject" title="PyArrayObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyArrayObject</span> <span class="pre">*</span></code></a> variable is a pointer to a particular instance
of an ndarray (one of the members of the ndarray structure is, in
turn, a pointer to the type- object table <a class="reference internal" href="../reference/c-api/types-and-structures.html#c.PyArray_Type" title="PyArray_Type"><code class="xref c c-data docutils literal notranslate"><span class="pre">&amp;PyArray_Type</span></code></a>). Finally
<a class="reference external" href="https://docs.python.org/dev/c-api/type.html#c.PyType_Ready" title="(in Python v3.9)"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Ready</span></code></a> (&lt;pointer_to_type_object&gt;) must be called for
every new Python type.</p>
<div class="section" id="creating-sub-types">
<h3>Creating sub-types<a class="headerlink" href="#creating-sub-types" title="Permalink to this headline">¶</a></h3>
<p>To create a sub-type, a similar procedure must be followed except
only behaviors that are different require new entries in the type-
object structure. All other entries can be NULL and will be filled in
by <a class="reference external" href="https://docs.python.org/dev/c-api/type.html#c.PyType_Ready" title="(in Python v3.9)"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Ready</span></code></a> with appropriate functions from the parent
type(s). In particular, to create a sub-type in C follow these steps:</p>
<ol class="arabic">
<li><p>If needed create a new C-structure to handle each instance of your
type. A typical C-structure would be:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="n">_new_struct</span> <span class="p">{</span>
    <span class="n">PyArrayObject</span> <span class="n">base</span><span class="p">;</span>
    <span class="cm">/* new things here */</span>
<span class="p">}</span> <span class="n">NewArrayObject</span><span class="p">;</span>
</pre></div>
</div>
<p>Notice that the full PyArrayObject is used as the first entry in order
to ensure that the binary layout of instances of the new type is
identical to the PyArrayObject.</p>
</li>
<li><p>Fill in a new Python type-object structure with pointers to new
functions that will over-ride the default behavior while leaving any
function that should remain the same unfilled (or NULL). The tp_name
element should be different.</p></li>
<li><p>Fill in the tp_base member of the new type-object structure with a
pointer to the (main) parent type object. For multiple-inheritance,
also fill in the tp_bases member with a tuple containing all of the
parent objects in the order they should be used to define inheritance.
Remember, all parent-types must have the same C-structure for multiple
inheritance to work properly.</p></li>
<li><p>Call <a class="reference external" href="https://docs.python.org/dev/c-api/type.html#c.PyType_Ready" title="(in Python v3.9)"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Ready</span></code></a> (&lt;pointer_to_new_type&gt;). If this function
returns a negative number, a failure occurred and the type is not
initialized. Otherwise, the type is ready to be used. It is
generally important to place a reference to the new type into the
module dictionary so it can be accessed from Python.</p></li>
</ol>
<p>More information on creating sub-types in C can be learned by reading
PEP 253 (available at <a class="reference external" href="https://www.python.org/dev/peps/pep-0253">https://www.python.org/dev/peps/pep-0253</a>).</p>
</div>
<div class="section" id="specific-features-of-ndarray-sub-typing">
<h3>Specific features of ndarray sub-typing<a class="headerlink" href="#specific-features-of-ndarray-sub-typing" title="Permalink to this headline">¶</a></h3>
<p>Some special methods and attributes are used by arrays in order to
facilitate the interoperation of sub-types with the base ndarray type.</p>
<div class="section" id="the-array-finalize-method">
<h4>The __array_finalize__ method<a class="headerlink" href="#the-array-finalize-method" title="Permalink to this headline">¶</a></h4>
<dl class="attribute">
<dt id="ndarray.__array_finalize__">
<code class="sig-prename descclassname">ndarray.</code><code class="sig-name descname">__array_finalize__</code><a class="headerlink" href="#ndarray.__array_finalize__" title="Permalink to this definition">¶</a></dt>
<dd><p>Several array-creation functions of the ndarray allow
specification of a particular sub-type to be created. This allows
sub-types to be handled seamlessly in many routines. When a
sub-type is created in such a fashion, however, neither the
__new__ method nor the __init__ method gets called. Instead, the
sub-type is allocated and the appropriate instance-structure
members are filled in. Finally, the <a class="reference internal" href="../reference/arrays.classes.html#numpy.class.__array_finalize__" title="numpy.class.__array_finalize__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">__array_finalize__</span></code></a>
attribute is looked-up in the object dictionary. If it is present
and not None, then it can be either a CObject containing a pointer
to a <code class="xref c c-func docutils literal notranslate"><span class="pre">PyArray_FinalizeFunc</span></code> or it can be a method taking a
single argument (which could be None).</p>
<p>If the <a class="reference internal" href="../reference/arrays.classes.html#numpy.class.__array_finalize__" title="numpy.class.__array_finalize__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">__array_finalize__</span></code></a> attribute is a CObject, then the pointer
must be a pointer to a function with the signature:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="p">(</span><span class="n">PyArrayObject</span> <span class="o">*</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="p">)</span>
</pre></div>
</div>
<p>The first argument is the newly created sub-type. The second argument
(if not NULL) is the “parent” array (if the array was created using
slicing or some other operation where a clearly-distinguishable parent
is present). This routine can do anything it wants to. It should
return a -1 on error and 0 otherwise.</p>
<p>If the <a class="reference internal" href="../reference/arrays.classes.html#numpy.class.__array_finalize__" title="numpy.class.__array_finalize__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">__array_finalize__</span></code></a> attribute is not None nor a CObject,
then it must be a Python method that takes the parent array as an
argument (which could be None if there is no parent), and returns
nothing. Errors in this method will be caught and handled.</p>
</dd></dl>

</div>
<div class="section" id="the-array-priority-attribute">
<h4>The __array_priority__ attribute<a class="headerlink" href="#the-array-priority-attribute" title="Permalink to this headline">¶</a></h4>
<dl class="attribute">
<dt id="ndarray.__array_priority__">
<code class="sig-prename descclassname">ndarray.</code><code class="sig-name descname">__array_priority__</code><a class="headerlink" href="#ndarray.__array_priority__" title="Permalink to this definition">¶</a></dt>
<dd><p>This attribute allows simple but flexible determination of which sub-
type should be considered “primary” when an operation involving two or
more sub-types arises. In operations where different sub-types are
being used, the sub-type with the largest <a class="reference internal" href="../reference/arrays.classes.html#numpy.class.__array_priority__" title="numpy.class.__array_priority__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">__array_priority__</span></code></a>
attribute will determine the sub-type of the output(s). If two sub-
types have the same <a class="reference internal" href="../reference/arrays.classes.html#numpy.class.__array_priority__" title="numpy.class.__array_priority__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">__array_priority__</span></code></a> then the sub-type of the
first argument determines the output. The default
<a class="reference internal" href="../reference/arrays.classes.html#numpy.class.__array_priority__" title="numpy.class.__array_priority__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">__array_priority__</span></code></a> attribute returns a value of 0.0 for the base
ndarray type and 1.0 for a sub-type. This attribute can also be
defined by objects that are not sub-types of the ndarray and can be
used to determine which <a class="reference internal" href="../reference/arrays.classes.html#numpy.class.__array_wrap__" title="numpy.class.__array_wrap__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">__array_wrap__</span></code></a> method should be called for
the return output.</p>
</dd></dl>

</div>
<div class="section" id="the-array-wrap-method">
<h4>The __array_wrap__ method<a class="headerlink" href="#the-array-wrap-method" title="Permalink to this headline">¶</a></h4>
<dl class="attribute">
<dt id="ndarray.__array_wrap__">
<code class="sig-prename descclassname">ndarray.</code><code class="sig-name descname">__array_wrap__</code><a class="headerlink" href="#ndarray.__array_wrap__" title="Permalink to this definition">¶</a></dt>
<dd><p>Any class or type can define this method which should take an ndarray
argument and return an instance of the type. It can be seen as the
opposite of the <a class="reference internal" href="../reference/arrays.classes.html#numpy.class.__array__" title="numpy.class.__array__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">__array__</span></code></a> method. This method is used by the
ufuncs (and other NumPy functions) to allow other objects to pass
through. For Python &gt;2.4, it can also be used to write a decorator
that converts a function that works only with ndarrays to one that
works with any type with <a class="reference internal" href="../reference/arrays.classes.html#numpy.class.__array__" title="numpy.class.__array__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">__array__</span></code></a> and <a class="reference internal" href="../reference/arrays.classes.html#numpy.class.__array_wrap__" title="numpy.class.__array_wrap__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">__array_wrap__</span></code></a> methods.</p>
</dd></dl>

<span class="target" id="index-6"></span></div>
</div>
</div>
</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>